
<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta charset="utf-8" />
    <title>Running a single calculation &#8212; iprPy 0.10.2 documentation</title>
    <link rel="stylesheet" href="../_static/basic.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>
    <script crossorigin="anonymous" integrity="sha256-Ae2Vz/4ePdIu6ZyI/5ZGsYnb+m0JlOmKPjt6XZ9JJkA=" type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>
    <script async="async" type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
    <script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"inlineMath": [["$", "$"], ["\\(", "\\)"]], "processEscapes": true, "ignoreClass": "document", "processClass": "math|output_area"}})</script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Run a Jupyter Calculation Notebook" href="notebook.html" />
    <link rel="prev" title="Calculations" href="index.html" /> 
  </head><body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="notebook.html" title="Run a Jupyter Calculation Notebook"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="index.html" title="Calculations"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../index.html">iprPy 0.10.2 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Calculations</a> &#187;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="running-a-single-calculation">
<h1>Running a single calculation<a class="headerlink" href="#running-a-single-calculation" title="Permalink to this headline">¶</a></h1>
<p>This page describes the ways that a single calculation can be executed.</p>
<div class="section" id="calculation-script">
<h2>Calculation script<a class="headerlink" href="#calculation-script" title="Permalink to this headline">¶</a></h2>
<p>One easy way to run calculations is to execute the scripts directly</p>
<ol class="arabic">
<li><p>All calculation styles implemented in iprPy can be found in
<strong>iprPy/calculation/[style]</strong> directories.</p></li>
<li><p>Each calculation has a <strong>README.md</strong> file documenting what the calculation
does and a <strong>theory.md</strong> file providing more details of the theory and
methodology.  Read these files to learn what the calculations do and select
which one to run.</p></li>
<li><p>It is recommended to then copy the calculation style’s folder to another
location.  This is not necessary, but it will avoid the original folder
becoming cluttered with files generated by the calculation.</p></li>
<li><p>Read the <strong>parameters.md</strong> within the directory to learn about the input
parameters used by the calculation and their default values if not
specified.</p></li>
<li><p>Edit <strong>calc_[style].in</strong> within the directory by providing values for the
parameters.  See below for more details on the input file parsing rules.</p></li>
<li><p>In a terminal, cd to the calculation folder you created, and enter</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python calc<span class="se">\_</span><span class="o">[</span>style<span class="o">]</span>.py calc<span class="se">\_</span><span class="o">[</span>style<span class="o">]</span>.in
</pre></div>
</div>
</li>
<li><p>When the calculation finishes successfully, a <strong>record.json</strong> record file
will be created containing the processed results.</p></li>
<li><p>The results can then be viewed either by opening results.json in a text
editor or by loading the file within Python as an iprPy Record.</p></li>
</ol>
<div class="section" id="calculation-input-file-rules">
<h3>Calculation input file rules<a class="headerlink" href="#calculation-input-file-rules" title="Permalink to this headline">¶</a></h3>
<p>All of the calculation scripts read and interpret the input files using the
same basic rules</p>
<ul class="simple">
<li><p>The parameters are given in key-value format, with each line listing a
parameter followed by its assigned value.</p></li>
<li><p>Any parameters that are not listed or not given values will be ignored and be
given default values, if allowed by the calculation.</p></li>
<li><p>Any terms listed after a # will be treated as comments and ignored.</p></li>
<li><p>Only one value can be assigned to each parameter.  In other words, excluding
comment lines and empty value lines each input key can only appear once.</p></li>
</ul>
</div>
</div>
<div class="section" id="call-from-python">
<h2>Call from Python<a class="headerlink" href="#call-from-python" title="Permalink to this headline">¶</a></h2>
<p>A calculation style can also be accessed and called from within Python using
the associated Calculation subclass.  The Calculation subclasses can be
retrieved using the load_calculation() function.  For example, to load the
E_vs_r_scan calculation style</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">iprPy</span>
<span class="n">calc</span> <span class="o">=</span> <span class="n">iprPy</span><span class="o">.</span><span class="n">load_calculation</span><span class="p">([</span><span class="s1">&#39;E_vs_r_scan&#39;</span><span class="p">])</span>
</pre></div>
</div>
<p>The Calculation subclasses have a number of methods that can then be used to
explore and execute the calculations.</p>
<ul class="simple">
<li><p><strong>Calculation.main()</strong> calls the main function of the calculation and takes
an input parameter file as the first argument.  Upon successful completion, a
results.json record file will be created containing the processed
results.  Calling Calculation.main() is the same as running the script as
described above.</p></li>
<li><p><strong>Calculation.calc()</strong> is a shortcut to the calculation style’s primary
function.  This allows for the calculation method to be accessed directly
and be executed using already generated Python objects rather than
interpreting an input file to build the objects.  This function also returns
the calculation’s results as a Python dictionary rather than generating the
results.json file.  Details on the function, including the allowed parameters
and names of the returned results, can be found in the method’s docstring.</p></li>
<li><p><strong>Calculation.template()</strong> builds a template version of the input file that
can be used to generate a complete input parameter file from a Python
dictionary (using iprPy.tools.filltemplate()).</p></li>
<li><p><strong>Calculation.process_input()</strong> accesses the function used by
Calculation.main() that converts the input parameter file into a dictionary
of Python objects.  The generated Python objects can then be passed to
Calculation.calc().</p></li>
<li><p><strong>Calculation.allkeys</strong> is a list of the input parameter keys that
Calculation.process_input() recognizes.</p></li>
<li><p><strong>Calculation.directory</strong> is the path to the iprPy/calculation/[style]
directory.</p></li>
<li><p><strong>Calculation.files</strong> list the paths to all files in Calculation.directory
that are required to run the calculation style.</p></li>
</ul>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../index.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Running a single calculation</a><ul>
<li><a class="reference internal" href="#calculation-script">Calculation script</a><ul>
<li><a class="reference internal" href="#calculation-input-file-rules">Calculation input file rules</a></li>
</ul>
</li>
<li><a class="reference internal" href="#call-from-python">Call from Python</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="index.html"
                        title="previous chapter">Calculations</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="notebook.html"
                        title="next chapter">Run a Jupyter Calculation Notebook</a></p>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="notebook.html" title="Run a Jupyter Calculation Notebook"
             >next</a> |</li>
        <li class="right" >
          <a href="index.html" title="Calculations"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../index.html">iprPy 0.10.2 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="index.html" >Calculations</a> &#187;</li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.1.2.
    </div>
  </body>
</html>